/*******************************************************************************
 * -------
 *   Copyright 2011 @ Fluid India Consultancy
 *   All Rights Reserved
 * -------
 ******************************************************************************/
package org.fluidindia.security.service;

import org.fluidindia.security.vo.LoginVO;

public interface ISecurityService
{
    /**
     * <p>
     * Logs a valid user into the system. A user will be logged in if following conditions meet:
     * <ul>
     * <li>Username exists in the system.</li>
     * <li>Password should match with the one stored in the data store. Password will have to be matched against a
     * one-way encrypted secure value.</li>
     * </ul>
     * </p>
     * 
     * @param request - Contains user credentials.
     * @return An object of {@link LoginVO} with a <code>sessionId</code> only if the user has logged in successfully.
     *         If a user was not able to login successful, response will contain the respective error messages.
     */
    LoginVO login(String username, String password);


    /**
     * <p>
     * This method kills an active session for the user that is associated with a unique token that is send as a
     * parameter to this method.
     * </p>
     * 
     * @param userToken
     */
    void logout(String userToken);


    /**
     * <p>
     * Finds the permissions for a user in the system.
     * </p>
     * 
     * <p>
     * The requester has to provide a Unique User token which will be used to locate an active user session in the
     * system. This token is generated with the user logs in to the application using the
     * {@link ISecurityService#login(String, String)} command. This method if successful returns a token in the
     * {@link LoginVO#getUserToken()} method which need to be passed back here.
     * </p>
     * 
     * 
     * @param userToken - a {@link String} that represents an active session in the application.
     */
    // TODO: Need to define a Domain Object for getUserPermissions
    void getUserPermissions(String userToken);


    /**
     * <p>
     * Checks if a user has a specific permission in the application. The
     * </p>
     * 
     * @param userToken - A {@link String} representing a unique token to identify an active user session
     * @param artifactId - A {@link String} representing an Artifact on which the permission needs to be checked
     * @param permission - A {@link String} representing a Permission that needs to be checked for
     * 
     * @return - <code>true</code> if user has the permission, else <code>false</code>
     * 
     */
    Boolean hasPermission(String userToken, String artifactId, String permission);


    /**
     * <p>
     * Finds all the Roles defined in the Application
     * </p>
     * 
     */
    // TODO: Need to define a Domain Object for getRoles
    void getRoles();


    /**
     * <p>
     * Gets all the artifacts for a specific category that have been defined in the application
     * </p>
     * 
     * @param category - A {@link String} representing a category for which the artifacts need to be retreived.
     */
    // TODO: Need to define a Domain Object for getArtifacts
    void getArtifacts(String category);
}
